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Intellectual Property Rights 



IPRs essential or potentially essential to the present document may have been declared to ETSI. The information 
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found 
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in 
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web 
server ( http://webapp.etsi.org/IPR/home.asp) . 

Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee 
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web 
server) which are, or may be, or may become, essential to the present document. 



Foreword 

This Technical Specification (TS) has been produced by ETSI Technical Conmiittee Smart Card Platform (SCP). 

The contents of the present document are subject to continuing work within TC SCP and may change following formal 
TC SCP approval. If TC SCP modifies the contents of the present document, it will then be republished by ETSI with 
an identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

early working draft; 

1 presented to TC SCP for information; 

2 presented to TC SCP for approval; 

3 or greater indicates TC SCP approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 
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Scope 



The present document describes the UICC AppHcation Programming Interface for Java Card^^ for contactless 
AppHcations. Its purpose is to provide access for a contactless Applet to the services provided by the HCI protocol 
defined in [4] for the communication via the CLF. In the scope of this document contactless means support for the RF 
Technologies referenced by the HCI specification [4] . Low level functionality to manage gates and pipes as defined in 
the HCI specification [4] is not in the scope of this document. Registration of contactless parameters and management 
of contactless Applets in card emulation mode is defined in "GlobalPlatform Amendment C" [8]. 



2 References 

References are either specific (identified by date of publication and/or edition number or version number) or 
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the 
reference document (including any amendments) applies. 

• In the case of a reference to a TC SCP document, a non specific reference implicitly refers to the latest version 
of that document in the same Release as the present document. 

Referenced documents which are not found to be publicly available in the expected location might be found at 
http ://docbox . etsi . or g/Ref erence . 

NOTE: While any hyperlinks included in this clause were valid at the time of publication ETSI cannot guarantee 
their long term validity. 



2.1 



Normative references 



The following referenced documents are necessary for the application of the present document. 



[1] 

[2] 
[3] 

[4] 

[5] 

[6] 
[7] 
[8] 



ISO/IEC 7816-3:2006: "Identification cards - Integrated circuit cards - Part 3: Cards with contacts 
- Electrical interface and transmission protocols". 

ETSI TS 102 221: "Smart Cards; UICC-Terminal interface; Physical and logical characteristics". 

ETSI TS 101 220: "Smart Cards; ETSI numbering system for telecommunication application 
providers". 

ETSI TS 102 622: "Smart Cards; UICC - Contactless Front-end (CLF) Interface; Host Controller 
Interface (HCI)". 

ETSI TS 102 241: "Smart Cards; UICC Application Programming Interface (UICC API) for Java 
Card(TM)". 

ETSI TS 102 223: "Smart Cards; Card Application Toolkit (CAT)". 

ETSI TS 102 226: "Smart Cards; Remote APDU structure for UICC based appHcations". 

GlobalPlatform: "GlobalPlatform Card Specification Version 2.2, Amendment C: Contactless 
Services" Version 1.0. 



NOTE: See http://www.globalplatform.org/ . 



[9] 
[10] 



Sun Microsystems "Application Programming Interface, Java Card^^ Platform, 3.0.1 Classic 
Edition" . 

Sun Microsystems "Runtime Environment Specification, Java Card^^ Platform, 3.0.1 Classic 
Edition" . 



[11] Sun Microsystems "Virtual Machine Specification Java Card^^ Platform, 3.0.1 Classic Edition". 

NOTE: SUN Java Card Specifications can be downloaded at http ://j ava. sun.com/products/j avacard/specs.html . 
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2.2 Informative references 

The following referenced documents are not necessary for the application of the present document but they assist the 
user with regard to a particular subject area. 

Not applicable. 



3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the following terms and definitions apply: 
contactless mode: is used as a generic term for "Card Emulation Mode" and "Reader Mode" 
HCP message: message as specified in TS 102 622 [4] 

NOTE: An HCP message can be of type "command", "event" or "response to a command" 
RF Technology: radio frequency technology supported by the HCI (TS 102 622 [4]) protocol specification 

3.2 Abbreviations 

For the purposes of the present document, the following abbreviations apply: 

APDU Application Protocol Data Unit 

NOTE: According to ISO/IEC 7816-3 [1]. 

API Application Programming Interface 

CLE Contactless Eront-end 

NOTE: According to TS 102 622 [4]. 

HCI Host Controller Interface 

NOTE: According to TS 102 622 [4]. 

HCP Host Controller Protocol 

NOTE: According to TS 102 622 [4]. 

RE Radio Frequency 



4 Description 

4.1 Arciiitecture 

The present document describes an API and a Contactless Framework that enables Java Card^^ Platform based 
Applets, defined in [9], [10] and [11], to send and receive messages using the HCI protocol as specified in 
TS 102 622 [4] and to act as contactless Applets. The Contactless Framework shall support card emulation mode and 
reader mode as specified in the HCI protocol (TS 102 622 [4]) specification. 
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CardEmulation 
Mode Applets 



Reader Mode 
Applets 



uicc.hci.framework 
package 



uicc.hci.service.* 
packages 



Java Card Runtime Environment 



CL Registry 



Contactless 
Framework 



Items that are defined in this specification 
vyyyyJ Items that are defined GP Amendment C 



Figure 1 

The API is event driven and based on the Observer/Listener pattern. Every HCI service is encapsulated by a dedicated 
Service interface. These Service interfaces shall allow the registration of Listener Interfaces and the activation of 
events. The Listener Interfaces shall be implemented by Java objects to receive HCI messages and events in the 
onCallback method. The Registration of Listener Interfaces and activation of events shall be persistent. 

An HCIMessage object shall encapsulates one HCP message according to the HCI protocol as specified in 

TS 102 622 [4]. HCI message for the different contactless modes shall be identified by different types of interfaces. It is 

not guaranteed that any Applet originated HCI messages are sent before the completion of the execution of the current 

Applet. 

Any onCallbackO method of a Listener interface shall not be invoked again while another onCallback() method is still 
being executed. The Contactless Framework shall be able to receive one or more HCI messages while waiting for a 
response related to a command originated by the Applet (e.g. processing a request for parameters) especially for the 
EVT_FIELD_OFF case. 

The HCI event EVT_FIELD_OFF shall be buffered and sent by the Contactless Framework as soon as the Contactless 
Framework becomes the current context. 

All other HCI messages shall be delivered to the Applet instance in the same order as they were received by the 
Contactless Framework. 

When the contactless interface is disabled (cf. "state of contactless functionality" in TS 102 223 [6] and 
setCommunicationlnterfaceO API method of "GlobalPlatform Amendment C" [8]), the Contactless Framework shall 
throw an HCIException with reason code HCI_CURRENTLY_DISABLED. 

The API is split into two parts. One is a generic framework that provides a factory class to retrieve the different Service 
instances that are provided by the HCI implementation, and that allows discovery of whether the UICC is inserted into a 
HCI network. The second part of the API implements the Services that are defined for the HCI protocol, card emulation 
mode, reader mode and connectivity service. 
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As stated in TS 102 622 [4], a reset of the underlying data link layer shall be transparent to the application layer if the 
data Hnk layer recovers without any loss of data. In the case of a data loss an error shall be reported back to the 
Application which has initiated the data transmission. In case of a communication in CardEmulation Mode where a 
command from an external reader can not be forwarded to an Application due to a data link layer problem the 
Contactless Framework shall not take any action but wait for the reader to resolve the problem. 

4.2 Card Emulation Mode 

In card emulation mode there exist two exclusive ways to exchange messages over the HCP [4] . The first is based on 
APDUs provided to the Applet through its process() method as specified in "Application Programming Interface, Java 
Card^M Platform, 3.0 Classic Edition" [9]. The second is made available by the package uicc.hci.services.cardemulation 
defined in this specification. 

The uicc.hci.services.cardemulation package shall provide the communication technologies for the card emulation 
mode defined by the HCP as specified in [4]. The Contactless Framework shall bind the services defined in the 
uicc.hci.services.cardemulation package to the underlying HCI resources (e.g. gates and pipes) defined in the HCI 
architecture as specified in [4] . The parameters to be used by the HCI layer may be provided to the framework as 
defined in "GlobalPlatform Amendment C" [8]. 

For the API defined in this specification the card emulation capability shall be provided to Applets through a service 
interface implemented by the Contactless Framework. Applet instances shall receive CardEmulationMes sages after the 
registration of a CardEmulationListener interface to a CardEmulationService only if the EVENT_ON_SEND_DATA is 
activated for the Applet instance. If the EVENT_ON_SEND_DATA is deactivated for the Applet instance and an 
APDU is received via the EVT_SEND_DATA, the javacard.framework.APDU class and the process() method of the 
Applet instance shall be invoked. 

It shall not be possible to switch between the usage of the CardEmulationListener interface and the invocation through 
the processO method within a contactless application session, i.e. not before the Applet has been deselected and 
selected again. Applets communicating through the process() method shall also be able to use the API services defined 
in this specification which do not require a CardEmulationListener registration (e.g. requesting the power mode or 
connectivity service). 

If the current application was selected through a SELECT by DF name, the Contactless Framework shall handle an 
application session termination according to TS 102 221 [2] independent of the interface used for APDU exchange. 

Applet selection and deselection shall be performed by the Contactless Framework according to the rules defined in the 
"Java Card^^ Runtime Environment Specification, 3.0.1 Classic Edition" [10] and in "GlobalPlatform Amendment C" 
[8]. 

The selectO method of the Applet instance shall always be invoked for an Applet selection according to the rules given 
in "Java Card^^ Runtime Environment Specification, 3.0.1 Classic Edition" [10]. 

In case the Applet instance has registered the CardEmulationListener and has activated the 

EVENT_ON_SEND_DATA the process() method of this Applet instance shall not be invoked during the selection. The 
CardEmulationListener. onCallhack method shall be called by the Contactless Framework. The HCP message that 
resulted in the selection of this Applet according to the rules defined in "GlobalPlatform Amendment C" [8] shall be 
provided by the CardEmulationMes sage. 

If the HCI event EVT_FIELD_OFF or EVT_CARD_DE ACTIVATED defined by the HCP specified in TS 102 622 [4] 
is received by the Contactless Framework and the UICC is still powered, the Applet instance shall be deselected 
according to "GlobalPlatform Amendment C" [8] by invocation of the deselect() method. 

When the HCI event EVT_FIELD_OFF is received and if the Applet instance has activated this event the Contactless 
Framework shall raise an EVENT_FIELD_OFF before the invocation of the deselect() method of the Applet instance. 

After the deselection of the Applet instance, it shall not be invoked by any other event defined in the interface 
CardEmulationListener until the Applet instance is selected again. 
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4.3 Reader Mode 

The functionality to support the reader mode is provided in the package uicc.hcLservices. reader. In reader mode the 
conmiunication technologies defined by the contactless platform for reader mode [4] are supported. The Contactless 
Framework shall bind the services defined in uicc.hcLservices. reader to the corresponding resources (e.g. gates and 
pipes) defined by the contactless platform for reader mode [4] . 

An Applet has to be in the selectable state (according to the Java Card^^ specification [9], [10] and [1 1]) to act as a 
contactless Applet in reader mode. 

Reader mode Applets shall follow the extended lifecycle model that is defined in "GlobalPlatform Amendment C" [8] 
for contactless Applets in card emulation mode (i.e. following Application Availability States and the related transition 
rules). 

Per RF technology there shall be only one reader mode Applet in the state ACTIVATED (according to "GlobalPlatform 
Amendment C" [8]) at any time. 

The installation parameters for contactless reader mode applications are specified in TS 102 226 [7]. 

When the state of a reader mode Applet changes to lifecycle ACTIVATED (according to "GlobalPlatform 
Amendment C" [8]) the Contactless Framework shall ensure that the HCI gates and pipes are setup for the RF 
technologies that are supported by the reader mode Applet. 

To be able to receive and send messages over the contactless interface in reader mode the Applet shall activate the 
ReaderListener.EVENT_TARGET_DISCOVERED. An Applet shall only be able to activate this event or to use the 
restartReadermodeProcedure method if it is in lifecycle state ACTIVATED. To release the CLE control at the end of a 
transaction an Applet shall deactivate the ReaderListener.EVENT_TARGET_DISCOVERED. 

When an Applet lifecycle state changes from ACTIVATED to DEACTIVATED the Contactless Framework shall 
enforce that the ReaderListener.EVENT_TARGET_DISCOVERED is deactivated. 

The Contactless Framework shall request the reader mode control on the CLE by sending the HCI events 
EVT_READER_REQUESTED and EVT_END_OPERATION according to the state of the reader mode Applet. The 
EVT_READER_REQUESTED shall be sent by the Contactless Framework if an Applet instance activates the event 
ReaderListener.EVENT_TARGET_DISCOVERED and no other Applet instance has the event activated, i.e. it shall not 
be sent if the Contactless Framework has earlier sent an EVT_READER_REQUESTED due to the request from another 
Applet instance, which was not yet ended by an EVT_END_OPERATION. The HCI event EVT_END_OPERATION 
shall be sent to the CLE when an Applet instance or the Contactless Framework deactivates the event 
ReaderListener.EVENT_TARGET_DISCOVERED. The Contactless Framework shall resend the 
EVT_READER_REQUESTED to the CLE if another Applet instance exists with the 
ReaderListener.EVENT_TARGET_DISCOVERED event activated. 

The Contactless Framework shall inform the Applet instance which has activated the 

ReaderListener.EVENT_TARGET_DISCOVERED when a target is discovered on one of the RF technologies the Applet 
instance is registered to with its installation parameters as specified in TS 102 226 [7]. 

The Contactless Framework shall ensure that the ReaderListener.EVENT_TARGET_DISCOVERED is deactivated for 
all Applets when access to the interface is disabled on the UICC level. 



4.4 Connectivity Service 



The functionality to support the connectivity mechanisms specified in the HCI specification [4] is provided in the 
package nice. hci. services. connectivity. The Contactless Framework shall bind the services defined in 
uicc.hci.services. connectivity to the corresponding resources (e.g. gates and pipes) specified in the HCI specification [4] 
for connectivity. 

The Contactless Framework shall only accept the request to send the HCI event EVT_CONNECTIVITY or 
EVT_TRANS ACTION specified by the HCP [4] when initiated by an Applet instance calling one of the 
ConnectivityService interface methods, if the Applet is the selected Applet in card emulation mode or is in the state 
ACTIVATED (according to "GlobalPlatform Amendment C" [8]) for the reader mode. 
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5 Interaction with Proactive Functionality 

The ProactiveHandler defined in TS 102 241 [5] shall not be available when the contactless Applet is invoked with the 
callback methods defined in this specification, or when the Applet is invoked with the process() method of the Applet 
class defined in Application Programming Interface, Java Card^^ Platform [9] (in card emulation mode). If the Applet 
wants to use proactive functionality it shall use the Connectivity Service defined above to send an HCI event 
EVT_CONNECTIVITY to the terminal, register for EVENT _EVENT_DOWNLO AD _HCI_CONNECTIVITY and return. 
All the proactive functionality of the UICC API defined in TS 102 241 [5] is then available to the Applet when that 
Applet instance is triggered with the processToolkit() method defined in TS 102 241 [5]. 



6 Java Card Resource Handling 

The Runtime Environment invokes an Applet by calling the onCallback() method of the respective contactless Listener 
Interface. As a consequence all the rules defined in "Java Card^^ Platform 3.0.1 Classic Edition, Runtime Environment 
Specification" [10] apply (e.g. access to CLEAR_ON_DESELECT transient objects, context switch, multi selectable). 

When the onCallback() method of a Listener Interface is invoked, no transaction shall be in progress. 

The context as defined in the Java Card^^ specification [9], [10] and [11] shall be set to the context of the Applet which 
implements the onCallback() method. The previous context (context of the caller) shall be the context of the Contactless 
Framework. 

Upon return from the onCallback() method a pending transaction shall be aborted. 
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Annex A (normative): 

Java Card™ Platform HCI API for the UICC 

The source files for the UICC AppHcation Programming Interface for Java Card^^ for contactless Applets 
(102705_Annex_A_Java.zip and 102705_Annex_A-HTML.zip) are contained in ts_102705v090100p0.zip, which 
accompanies the present document. 
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Annex B (normative): 

Java Card ™ platform HCI API for the UICC identifiers 

The export files for the uicc.hci.* package (102705_Annex_B_Export_Files.zip) are contained in 
ts_102705v090100p0.zip, which accompanies the present document. 
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Annex C (normative): 

HCI API package version management 

Table C.l describes the relationship between each TS 102 705 specification version and its HCI API packages AID and 
Major, Minor versions defined in the export files. 

Table C.l 



TS 102 705 


uicc.hci.framework package 




AID Major, Minor 


9.0.0 


AO 00 00 00 09 00 05 FF FF FF FF 89 1 6 01 00 00 1 .0 



Table C.2 



TS 102 705 


uicc.hci.services.cardemulation package 




AID 


Major, Minor 


9.0.0 


AO 00 00 00 09 00 05 FF FF FF FF 89 16 02 01 00 


1.0 



Table C.3 



TS 102 705 


uicc.hci.services.connectivity package 




AID 


Major, Minor 


9.0.0 


AO 00 00 00 09 00 05 FF FF FF FF 89 16 02 02 00 


1.0 



Table C.4 



TS 102 705 


uicc.hci.services.readermode packac 


le 




AID 


Major, Minor 


9.0.0 


AO 00 00 00 09 00 05 FF FF FF FF 89 16 02 03 00 


1.0 



The package AID coding is defined in TS 101 220 [3]. The HCI API packages' AIDs are not modified by changes to 
Major or Minor Version. 

The Major Version shall be incremented if a change to the specification introduces byte code incompatibility with the 
previous version. 

The Minor Version shall be incremented if a change to the specification does not introduce byte code incompatibility 
with the previous version. 
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Annex D (informative): 
Change history 



Meeting 


Document 


CR 


Rev 


Cat 


Title 


Resulting 
Version 


SCP#45 










First publication of the specification 


9.0.0 


SCP#46 


SCP(1 0)0286 


001 


1 
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Clarification about restartReaderModeProcedure method use 


9.1.0 


SCP#46 


SCP(1 0)0287 


002 


1 


F 


Wrong Reference in HCIDevice.java related to UICC power mode 


9.1.0 


SCP#46 


SCP(1 0)0288 


003 


- 


F 


Correction of wrong constant value and name 


9.1.0 


SCP#46 


SCP(1 0)0289 


004 


- 


F 


Clarification of contactless framework behaviour when HCI event 
EVT FIELD OFF is received 
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007 
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ConnectivityService 


9.1.0 


SCP#46 


SCP(1 0)0292 


008 


- 


F 


Clarification of use of HCI CURRENTLY DISABLED reason code 


9.1.0 


SCP#46 


SCP(1 0)0309 


006 


- 


F 


Handling of HCI data link layer reset by HCI Framework 
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